<?php

namespace Illuminate\Contracts\Events;

interface Dispatcher
{
    /**
     * 注册一个事件监听器
     *
     * @param  string|array $events 事件名
     * @param  mixed $listener 监听器
     * @return void
     */
    public function listen($events, $listener);

    /**
     * 确认给定的事件是否注册了监听器
     *
     * @param  string $eventName 事件名
     * @return bool
     */
    public function hasListeners($eventName);

    /**
     * 注册一个事件订阅者
     *
     * @param  object|string $subscriber 订阅者类名 | 订阅者对象
     * @return void
     */
    public function subscribe($subscriber);

    /**
     * 触发一个事件，并得到第一个非空响应
     *
     * @param  string|object $event 事件名 | 事件对象
     * @param  mixed $payload 事件参数
     * @return array|null
     */
    public function until($event, $payload = []);

    /**
     * 触发指定事件，并调用事件监听器
     *
     * @param  string|object $event 事件名 | 事件对象
     * @param  mixed $payload 监听器参数
     * @param  bool $halt 是否在接收到一个不为 null 的数据时，立即返回该数据
     * @return array|null
     */
    public function dispatch($event, $payload = [], $halt = false);

    /**
     * 推入一个延迟触发事件，并在使用 flush 调用该事件的时候使用指定的参数
     *
     * @param  string $event 延迟触发的事件名
     * @param  array $payload 指定参数
     * @return void
     */
    public function push($event, $payload = []);

    /**
     * 触发一组延迟调用的事件
     *
     * @param  string $event 事件名
     * @return void
     */
    public function flush($event);

    /**
     * 从事件调度程序中删除一组侦听器
     *
     * @param  string $event 事件名
     * @return void
     */
    public function forget($event);

    /**
     * 移除所有的延迟触发事件
     *
     * @return void
     */
    public function forgetPushed();
}
